Add OpenSpec design proposals for Omnigent-derived features#46
Merged
Conversation
Add docs/related-work-omnigent.md comparing AgentTower (non-invasive tmux observer/router) with Databricks' Omnigent meta-harness (agent wrapper/runtime), and record the Omnigent-derived feature ideas that fit AgentTower's model in the mvp-feature-sequence "Later Features" backlog and architecture.md V2 Scope. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_015SpYMhCsyyGMEyNrxkWGCc
Add docs/integration-tiers.md defining the per-agent connection ladder (Tier 0 tmux floor -> Tier 1 native harness hooks/MCP/stream-json -> Tier 2 Omnigent) with independent inbound/outbound axes. Settle the router-first division of labor: AgentTower stays the router (agents report in via hooks and an AgentTower-hosted MCP server), Omnigent is the puppet master for action-level driving. Adoption of pre-instrumented panes is first-class; both Tier-1 mechanisms bridge via the existing Unix socket so the no-network-listener invariant holds. Cross-reference the new model from related-work-omnigent.md (Omnigent = Tier 2) and add an ordered backlog to mvp-feature-sequence.md. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_015SpYMhCsyyGMEyNrxkWGCc
Revert the two direct doc commits (Omnigent comparison + derived backlog, and the connection-strength tiers model). The forward-looking scope was written straight into the canonical docs; it should instead go through an OpenSpec change proposal under openspec/changes/. Recreated there. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_015SpYMhCsyyGMEyNrxkWGCc
Add OpenSpec change agent-connection-tiers: proposal, design, tasks, and the agent-integration capability spec delta. Captures the per-agent connection ladder (Tier 0 tmux floor / Tier 1 native harness hooks+MCP / Tier 2 Omnigent hand-off), independent inbound/outbound axes, router-first boundary (AT routes; Omnigent puppet-masters), first-class pre-instrumented adoption, the no-network-listener invariant, and tier-independent outbound safety. Spec/design only; no code. Authored to OpenSpec file conventions by hand (no openspec CLI available in this environment). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_015SpYMhCsyyGMEyNrxkWGCc
Restore related-work-omnigent.md and integration-tiers.md as reference material with explicit "research only" banners. They record no committed scope and modify no canonical spec; adopted scope lives under openspec/changes/. Removed the stale "recorded in the backlog" claims (those canonical-doc edits were reverted) and reframed the Omnigent-derived features as candidate scope feeding a future OpenSpec proposal. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_015SpYMhCsyyGMEyNrxkWGCc
Add three OpenSpec changes derived from the Omnigent analysis, plus a roadmap tying the family to the existing agent-connection-tiers (A): - routing-policy-layers (B): layered global->agent->route delivery policies; deny-wins/min-wins resolution; decision auditing; FEAT-009 backward compatibility. Capability: routing-policy. - discovery-backends (D): pluggable DiscoveryBackend interface; bench discovery refactored as backend #1 (no behavior change); identity namespacing; per-backend degraded isolation; host-only tmux backend #2. - app-collaboration (C, V2): multi-operator app sessions with observer vs operator roles; shared consistent view; server-side co-drive enforcement; cross-session audit; explicit local-only boundary. E (mobile/remote) recorded as a gated non-goal; F (agent network-egress) as advisory-only. All four changes pass `openspec validate --strict`. Spec/design only; no code. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_015SpYMhCsyyGMEyNrxkWGCc
Reviewer's GuideSpec-only PR that adds four coordinated OpenSpec design/capability proposals (agent connection tiers, routing policy layers, discovery backends, and local-only app collaboration), plus supporting research notes and a coordination README, to formalize how AgentTower will integrate with Omnigent and future substrates without changing runtime behavior today. Sequence diagram for local app collaboration (watch vs co-drive)sequenceDiagram
actor Operator
actor Observer
participant AppClientOperator
participant AppClientObserver
participant AgentTowerDaemon
Operator->>AppClientOperator: start_ui()
AppClientOperator->>AgentTowerDaemon: app.hello(role=operator)
AgentTowerDaemon-->>AppClientOperator: session_id_operator
Observer->>AppClientObserver: start_ui()
AppClientObserver->>AgentTowerDaemon: app.hello(role=observer)
AgentTowerDaemon-->>AppClientObserver: session_id_observer
AppClientOperator->>AgentTowerDaemon: app.send_input(session_id_operator,...)
AgentTowerDaemon-->>AppClientOperator: delivery_accepted
AppClientObserver->>AgentTowerDaemon: app.send_input(session_id_observer,...)
AgentTowerDaemon-->>AppClientObserver: mutation_rejected
Flow diagram for layered routing/input delivery policiesflowchart LR
Request["Delivery request"] --> GlobalPolicy["Global policies\n(routing_enabled, kill switch)"]
GlobalPolicy -->|deny| Blocked["Block delivery\n(policy_blocked)"]
GlobalPolicy -->|allow| AgentPolicy["Per-agent policies"]
AgentPolicy -->|deny| Blocked
AgentPolicy -->|allow| RoutePolicy["Per-route policies"]
RoutePolicy -->|require-approval / quiet hold| Held["Hold pending\n(policy_held)"]
RoutePolicy -->|allow within caps| Allowed["Deliver message\n(policy_allowed)"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- There’s a fair bit of duplicated narrative between
docs/integration-tiers.mdandopenspec/changes/agent-connection-tiers/design.md; consider trimming the research note to just the extra comparative context and explicitly pointing readers at the design/spec for any authoritative description of tiers and roles to avoid future drift. - In the
discovery-backendsproposal/spec, it would help to be more explicit about the identity-key migration strategy for existing bench-only deployments (e.g., how and when existing rows get abench:prefix) so downstream schema changes have a clear, non-hand-wavy plan to follow.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- There’s a fair bit of duplicated narrative between `docs/integration-tiers.md` and `openspec/changes/agent-connection-tiers/design.md`; consider trimming the research note to just the extra comparative context and explicitly pointing readers at the design/spec for any authoritative description of tiers and roles to avoid future drift.
- In the `discovery-backends` proposal/spec, it would help to be more explicit about the identity-key migration strategy for existing bench-only deployments (e.g., how and when existing rows get a `bench:` prefix) so downstream schema changes have a clear, non-hand-wavy plan to follow.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
- integration-tiers.md: trim duplicated tier/role narrative now owned by the agent-connection-tiers OpenSpec change; keep only orientation + pointers + the extra comparative context, with the design/spec marked authoritative (avoids future drift). - discovery-backends: make the identity-key migration concrete — a one-time, idempotent, history-preserving stamp of existing rows to backend_id='bench' tied to the schema bump, plus a transition read-time shim for legacy keys. Add a backward-compat scenario and a migration task. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_015SpYMhCsyyGMEyNrxkWGCc
There was a problem hiding this comment.
Pull request overview
Adds a spec-only OpenSpec “change family” derived from the AgentTower ↔ Omnigent analysis, formalizing several future capability directions (tiered agent integration, layered routing/input-delivery policy, pluggable discovery substrates, and local-only multi-operator app collaboration) without shipping implementation code.
Changes:
- Add four coordinated OpenSpec change proposals (proposal/design/spec/tasks/README) for: agent connection tiers, routing-policy layers, discovery backends, and app collaboration.
- Add an
openspec/changes/README.mdroadmap documenting dependencies/build order and shared guardrails. - Add two research notes under
docs/to capture the Omnigent comparison and generalize the integration-tier model.
Reviewed changes
Copilot reviewed 25 out of 25 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| openspec/changes/README.md | Roadmap for the coordinated change family, dependencies, and shared guardrails. |
| openspec/changes/agent-connection-tiers/tasks.md | Task breakdown for spec acceptance + future phased implementation. |
| openspec/changes/agent-connection-tiers/specs/agent-integration/spec.md | Capability requirements for tiered per-agent integration with independent inbound/outbound negotiation. |
| openspec/changes/agent-connection-tiers/proposal.md | Motivation/scope/impact statement for the tier model. |
| openspec/changes/agent-connection-tiers/design.md | Design decisions and rationale for the tier ladder and router-first boundary. |
| openspec/changes/routing-policy-layers/.openspec.yaml | Per-change OpenSpec metadata. |
| openspec/changes/routing-policy-layers/tasks.md | Task breakdown for layered delivery policy spec + future implementation. |
| openspec/changes/routing-policy-layers/specs/routing-policy/spec.md | Capability requirements for layered, auditable, router-scoped delivery policies. |
| openspec/changes/routing-policy-layers/README.md | One-line change summary. |
| openspec/changes/routing-policy-layers/proposal.md | Motivation/scope/impact statement for policy layering. |
| openspec/changes/routing-policy-layers/design.md | Design decisions for precedence/merge rules, policy types, auditing, and backward-compat mapping. |
| openspec/changes/discovery-backends/.openspec.yaml | Per-change OpenSpec metadata. |
| openspec/changes/discovery-backends/tasks.md | Task breakdown for discovery backend abstraction + future implementation. |
| openspec/changes/discovery-backends/specs/discovery-backends/spec.md | Capability requirements for pluggable discovery substrates and degraded isolation. |
| openspec/changes/discovery-backends/README.md | One-line change summary. |
| openspec/changes/discovery-backends/proposal.md | Motivation/scope/impact statement for backend-pluggable discovery. |
| openspec/changes/discovery-backends/design.md | Design decisions for the backend interface and identity namespacing. |
| openspec/changes/app-collaboration/.openspec.yaml | Per-change OpenSpec metadata. |
| openspec/changes/app-collaboration/tasks.md | Task breakdown for multi-operator collaboration spec + future implementation. |
| openspec/changes/app-collaboration/specs/app-collaboration/spec.md | Capability requirements for observer/operator roles and local-only co-drive enforcement. |
| openspec/changes/app-collaboration/README.md | One-line change summary. |
| openspec/changes/app-collaboration/proposal.md | Motivation/scope/impact statement for app collaboration. |
| openspec/changes/app-collaboration/design.md | Design decisions for roles, shared view consistency, and server-side enforcement. |
| docs/related-work-omnigent.md | Research note comparing AgentTower vs Omnigent and extracting candidate ideas. |
| docs/integration-tiers.md | Research note generalizing the tier model beyond the Omnigent comparison. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- routing-policy-layers/design.md: resolve the contradictory resolution semantics — state the model is restrictive-only (deny-wins for allow/deny, min-wins for caps; global deny absolute), dropping the "most-specific-wins" wording that implied a specific allow could broaden. - routing-policy-layers/design.md: correct FEAT-009 queue terminology — require-approval maps onto the `blocked` state released via `queue approve`; there is no `approved` state. - routing-policy-layers/design.md: fix the `architecture.md` inline reference that had wrapped to `architecture. md`. - agent-connection-tiers: add the missing .openspec.yaml + README.md for consistency with the other three changes in the family. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_015SpYMhCsyyGMEyNrxkWGCc
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1b79ffebb3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
routing-policy-layers: - reword Layered policy resolution to most-restrictive-wins across all layers (deny-wins/min-wins); scope order is attribution-only, not outcome - name audit event tokens policy_allowed/policy_blocked/policy_held and scope policy audit to decisions where a user-defined policy participates, so the no-policy default path stays byte-identical (no extra events.jsonl) app-collaboration: - add default-observer + explicit server-side operator promotion (no client self-select; pre-role clients treated as observer); clarify it is a coordination control under same-host-UID, not a privilege boundary - name the rejection error: FEAT-011 permission_denied with details.reason="observer_read_only" (no new code) discovery-backends: - drop Omnigent from the opening scope statement (Omnigent is the Tier-2 hand-off in agent-connection-tiers, not a discovery backend) agent-connection-tiers: - rephrase the tooling note generically (no environment-specific detail) openspec/changes/README.md: - add owning bench per change (py-bench) per AGENTS.md Single-Bench Ownership; note app-collaboration's Flutter UI is a separate flutter-bench follow-up All four changes pass `openspec validate --strict`. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_015SpYMhCsyyGMEyNrxkWGCc
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 55da825240
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Comment on lines
+85
to
+87
| - **Backend #2 (host-only tmux):** enumerate the host user's tmux sockets | ||
| directly (no `docker exec`). Proves the interface and delivers the | ||
| long-deferred host-only discovery item. |
There was a problem hiding this comment.
For the host-only tmux backend, there is no container to satisfy the current registry contract: I checked the shipped schema, and panes/agents require container fields such as container_id, container_name, and container_user while app/dashboard reads also join through containers. Because this design makes host-only tmux a reference backend but says the data model changes only for identity namespacing, an implementer either has to invent synthetic container rows that change observable container/app surfaces or cannot persist host panes at all; please define the target/container sentinel or schema transition before making this an acceptance requirement.
Useful? React with 👍 / 👎.
Comment on lines
+56
to
+62
| 1. **At upgrade (one-time, in the schema migration that adds `backend_id`):** | ||
| every existing `agents` / `panes` / `log_offsets` row is stamped | ||
| `backend_id = 'bench'` in a single transaction, because pre-namespacing | ||
| discovery could only have come from the bench-container substrate. The | ||
| migration is **idempotent** (guarded by the schema version) and **history- | ||
| preserving** (it rewrites the key column in place; it does not delete or | ||
| re-create rows, so events, offsets, and queue references stay attached). |
There was a problem hiding this comment.
This migration plan stamps agents, panes, and log_offsets, but it leaves out log_attachments, which also stores the same pane composite key and is used for active attachment lookups and stale-attachment reconciliation. When backend_id becomes part of pane identity, existing FEAT-007 attachment rows would remain unnamespaced, so the promised history-preserving upgrade can lose or misassociate active attachments even though offsets and queue references survive.
Useful? React with 👍 / 👎.
Comment on lines
+51
to
+53
| - **require-approval** — hold delivery until an operator approves. This maps onto | ||
| the existing FEAT-009 queue model: the message sits in the `blocked` state and | ||
| is released to `queued`/`delivered` via `agenttower queue approve` (FEAT-009's |
There was a problem hiding this comment.
When require-approval, rate caps, or quiet holds put a delivery into the FEAT-009 blocked queue path, the shipped message_queue.block_reason CHECK still only accepts the FEAT-009 reasons (sender_role_not_permitted, target failures, kill_switch_off, operator_delayed). Since the handoff only calls out adding a policies table/evaluator, the first policy-held row would either violate the schema or be mislabeled as an unrelated block reason; add the queue-row/audit reason extension to this design.
Useful? React with 👍 / 👎.
Comment on lines
+68
to
+72
| When a user-defined policy participates in a decision, AgentTower emits one | ||
| `events.jsonl` record — `policy_allowed` / `policy_blocked` / `policy_held` — | ||
| carrying the deciding layer, the matched rule id, and the target/route. This | ||
| mirrors FEAT-010's `route_matched` / `route_skipped` auditability so the full | ||
| delivery chain stays inspectable via `agenttower events`. |
There was a problem hiding this comment.
agenttower events
This promises policy decisions stay inspectable via agenttower events, but the current CLI/socket events filters are closed to the FEAT-008 event types and events.list reads the SQLite events table, while this design only mentions emitting JSONL policy rows. In an implementation that follows these tasks, agenttower events --type policy_blocked will be rejected or return nothing even though policy_blocked was appended to JSONL; add the event-surface/schema work needed to expose these new audit types.
Useful? React with 👍 / 👎.
Comment on lines
+36
to
+39
| AgentTower SHALL support delivery policy types that a router can enforce: | ||
| per-target rate caps, require-approval holds, allow/deny by source role and | ||
| capability, and target-busy / quiet holds. Policies SHALL NOT attempt to govern | ||
| an agent's own shell, file, or network actions. |
There was a problem hiding this comment.
For direct sends, “source role + capability” can mean the sending agent, but FEAT-010 route deliveries also have the event source, the arbitrated master/sender, and the route_id. Without specifying which identity a source allow/deny evaluates for route-origin queue rows, a policy like “deny shell sources” can either block based on the slave that emitted the event or allow based on the master chosen to deliver it, producing inconsistent enforcement across direct and route deliveries.
Useful? React with 👍 / 👎.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR introduces a coordinated family of four OpenSpec design proposals derived from the AgentTower ↔ Omnigent analysis. These are spec-only changes (no implementation code) that formalize architectural decisions and capability requirements for future feature work.
Changes
Research & Analysis Documents
docs/related-work-omnigent.md— Comparison of AgentTower (observer/router) vs Omnigent (meta-harness), identifying where they complement rather than competedocs/integration-tiers.md— Research note on AgentTower's connection-strength model, generalizing the Omnigent comparison into a broader architectureOpenSpec Change Proposals (four independent but coordinated changes)
agent-connection-tiers — Foundation proposal defining a per-agent ladder from tmux floor (Tier 0) through native harness integration (Tier 1) to Omnigent hand-off (Tier 2). Settles two key decisions:
routing-policy-layers — Layered delivery policies (global → per-agent → per-route) with deterministic resolution, router-appropriate policy types (rate caps, require-approval, source/target allow/deny, quiet holds), and full audit trail. Composes with the tier-independent outbound safety gate.
discovery-backends — Pluggable discovery interface abstracting where panes/agents come from (bench containers, host-only tmux, future remote benches) behind one interface. Refactors existing bench-container discovery as the first backend with no behavior change.
app-collaboration — Multi-operator local-only app sessions with
observer(read-only) andoperator(mutating) roles, consistent shared live view, and server-side co-drive enforcement. Explicitly defers remote/URL sharing as a gated non-goal requiring authenticated transport.Each proposal includes:
proposal.md— Why the change, what changes, and scopedesign.md— Goals/non-goals, decisions with rationale, and decision detailsspecs/<capability>/spec.md— Formal requirements with scenariostasks.md— Spec authoring tasks (this change) and implementation hand-off (future features)README.md— One-line summaryCoordination Document
openspec/changes/README.md— Dependency graph and recommended build order (A → B → D → C), shared guardrails (no network listener, router-not-puppeteer, no host-absolute paths)Notable Details
https://claude.ai/code/session_015SpYMhCsyyGMEyNrxkWGCc
Summary by Sourcery
Introduce a family of OpenSpec design proposals and research notes that define AgentTower’s integration tiers, layered routing policies, pluggable discovery backends, and local multi-operator app collaboration, without shipping any implementation code.
New Features:
agent-integrationcapability spec for a tiered per-agent connection model from tmux floor through native harness integration to Omnigent hand-off, with independent inbound/outbound negotiation and preserved safety invariants.routing-policycapability spec for layered global, per-agent, and per-route delivery policies with router-scoped controls and full auditability.discovery-backendscapability spec and interface for pluggable discovery substrates, refactoring existing bench-container discovery into the first backend and paving the way for host-only tmux and future backends.app-collaborationcapability spec for local-only multi-operator app sessions with observer/operator roles, shared live view, and server-enforced co-drive semantics.Enhancements:
Documentation: